<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  

  
  <title>Spring boot api 生成工具 apiDoc vs swagger and JApiDocs | 山芋头</title>
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
  <meta name="description" content="曾经看过这样一个笑话：程序员最讨厌写文档，比这个还讨厌的事情就是，别人居然不写文档。  文档的确是个令猿头疼的东西哇，但是文档的重要性也是不言而喻。这里就给大家安利两款比较好用的接口文档生成工具：  apidoc 比较好用的静态生成工具，生成静态api文档非常合适； swagger功能强大的动态api工具，带有调试功能，knife4j是对swaggerUI封装的优化，更适合国人风格； Japid">
<meta property="og:type" content="article">
<meta property="og:title" content="Spring boot api 生成工具 apiDoc vs swagger and JApiDocs">
<meta property="og:url" content="https://bianchengme.gitee.io/2020/09/09/Spring-boot-api-%E7%94%9F%E6%88%90%E5%B7%A5%E5%85%B7-apiDoc-vs-swagger-and-JApiDocs/index.html">
<meta property="og:site_name" content="山芋头">
<meta property="og:description" content="曾经看过这样一个笑话：程序员最讨厌写文档，比这个还讨厌的事情就是，别人居然不写文档。  文档的确是个令猿头疼的东西哇，但是文档的重要性也是不言而喻。这里就给大家安利两款比较好用的接口文档生成工具：  apidoc 比较好用的静态生成工具，生成静态api文档非常合适； swagger功能强大的动态api工具，带有调试功能，knife4j是对swaggerUI封装的优化，更适合国人风格； Japid">
<meta property="og:locale" content="cn">
<meta property="og:image" content="https://note.youdao.com/yws/api/personal/file/3E3A42C7488F4B28A55A571E547E667E?method=download&shareKey=f4cb66a4dda2c461904f3d17ac6d480f">
<meta property="og:image" content="https://note.youdao.com/yws/api/personal/file/A32C6142B85F4DF5B6573298C86676F8?method=download&shareKey=0473103f88076c2f2e8890f7fca8a8f9">
<meta property="og:image" content="https://note.youdao.com/yws/api/personal/file/953F265590674B73989A418C301FFE67?method=download&shareKey=09939a1241d68066e42a2e3a3faec42b">
<meta property="og:image" content="https://note.youdao.com/yws/api/personal/file/8D095CF9E7CA47259ACB4DA34075E844?method=download&shareKey=9c3d003719cc502734c3739bbd6d5221">
<meta property="og:image" content="https://note.youdao.com/yws/api/personal/file/1C94F35AE9A24495A8E2D1699C376FF2?method=download&shareKey=f5202a26d0dfa4e0e7e3a84d1804703c">
<meta property="article:published_time" content="2020-09-09T14:19:23.000Z">
<meta property="article:modified_time" content="2021-09-07T07:26:31.782Z">
<meta property="article:author" content="jmme@foxmail.com">
<meta name="twitter:card" content="summary">
<meta name="twitter:image" content="https://note.youdao.com/yws/api/personal/file/3E3A42C7488F4B28A55A571E547E667E?method=download&shareKey=f4cb66a4dda2c461904f3d17ac6d480f">
  
    <link rel="alternate" href="/atom.xml" title="山芋头" type="application/atom+xml">
  
  
    <link rel="icon" href="/favicon.png">
  
  
    <link href="//fonts.googleapis.com/css?family=Source+Code+Pro" rel="stylesheet" type="text/css">
  
  
<link rel="stylesheet" href="/css/style.css">

<meta name="generator" content="Hexo 4.2.0"></head>

<body>
  <div id="container">
    <div id="wrap">
      <header id="header">
  <div id="banner"></div>
  <div id="header-outer" class="outer">
    <div id="header-title" class="inner">
      <h1 id="logo-wrap">
        <a href="/" id="logo">山芋头</a>
      </h1>
      
        <h2 id="subtitle-wrap">
          <a href="/" id="subtitle">记录和分享能创造价值</a>
        </h2>
      
    </div>
    <div id="header-inner" class="inner">
      <nav id="main-nav">
        <a id="main-nav-toggle" class="nav-icon"></a>
        
          <a class="main-nav-link" href="/">Home</a>
        
          <a class="main-nav-link" href="/archives">Archives</a>
        
      </nav>
      <nav id="sub-nav">
        
          <a id="nav-rss-link" class="nav-icon" href="/atom.xml" title="RSS Feed"></a>
        
        <a id="nav-search-btn" class="nav-icon" title="Search"></a>
      </nav>
      <div id="search-form-wrap">
        <form action="//google.com/search" method="get" accept-charset="UTF-8" class="search-form"><input type="search" name="q" class="search-form-input" placeholder="Search"><button type="submit" class="search-form-submit">&#xF002;</button><input type="hidden" name="sitesearch" value="https://bianchengme.gitee.io"></form>
      </div>
    </div>
  </div>
</header>
      <div class="outer">
        <section id="main"><article id="post-Spring-boot-api-生成工具-apiDoc-vs-swagger-and-JApiDocs" class="article article-type-post" itemscope itemprop="blogPost">
  <div class="article-meta">
    <a href="/2020/09/09/Spring-boot-api-%E7%94%9F%E6%88%90%E5%B7%A5%E5%85%B7-apiDoc-vs-swagger-and-JApiDocs/" class="article-date">
  <time datetime="2020-09-09T14:19:23.000Z" itemprop="datePublished">2020-09-09</time>
</a>
    
  </div>
  <div class="article-inner">
    
    
      <header class="article-header">
        
  
    <h1 class="article-title" itemprop="name">
      Spring boot api 生成工具 apiDoc vs swagger and JApiDocs
    </h1>
  

      </header>
    
    <div class="article-entry" itemprop="articleBody">
      
        <blockquote>
<p>曾经看过这样一个笑话：程序员最讨厌写文档，比这个还讨厌的事情就是，别人居然不写文档。</p>
</blockquote>
<p>文档的确是个令猿头疼的东西哇，但是文档的重要性也是不言而喻。这里就给大家安利两款比较好用的接口文档生成工具：</p>
<ul>
<li>apidoc 比较好用的静态生成工具，生成静态api文档非常合适；</li>
<li>swagger功能强大的动态api工具，带有调试功能，knife4j是对swaggerUI封装的优化，更适合国人风格；</li>
<li>Japidocs 新开源的静态生成工具用的人虽然没有上面两个多，但是只需要java环境即可，也是不错的api生成工具，值得尝试。</li>
</ul>
<h3 id="1-apidoc"><a href="#1-apidoc" class="headerlink" title="1. apidoc"></a>1. apidoc</h3><h5 id="简介"><a href="#简介" class="headerlink" title="简介"></a>简介</h5><p>apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。</p>
<h5 id="使用"><a href="#使用" class="headerlink" title="使用"></a>使用</h5><p>首先你的环境必须要安装了node.js.然后通过以下的命令安装apidoc：</p>
<blockquote>
<p>npm install apidoc -g</p>
</blockquote>
<p>在你的项目根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，例如标题、介绍、版本等。</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">&#123;</span><br><span class="line">  &quot;name&quot;: &quot;example&quot;,</span><br><span class="line">  &quot;version&quot;: &quot;0.1.0&quot;,</span><br><span class="line">  &quot;description&quot;: &quot;apiDoc basic example&quot;,</span><br><span class="line">  &quot;title&quot;: &quot;Custom apiDoc browser title&quot;,</span><br><span class="line">  &quot;url&quot; : &quot;https:&#x2F;&#x2F;api.github.com&#x2F;v1&quot;</span><br><span class="line">&#125;</span><br><span class="line">1234567</span><br></pre></td></tr></table></figure>

<p>在你的代码注释里加入apidoc的注解，例如这样子：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br></pre></td><td class="code"><pre><span class="line">    &#x2F;**</span><br><span class="line">     * @apiGroup Product</span><br><span class="line">     * @api &#123;GET&#125; &#x2F;product&#x2F;&#123;id&#125;  查询一个产品</span><br><span class="line">     * @apiDescription 指定产品id , 删除产品的全部信息，包括关联的schema</span><br><span class="line">     * @apiParam &#123;String&#125; id 产品id(必填*)</span><br><span class="line">     * @apiSuccessExample SuccessExample</span><br><span class="line">     * HTTP&#x2F;1.1 200</span><br><span class="line">     * &#123;</span><br><span class="line">     * id: &#39;xxx&#39;,</span><br><span class="line">     * modelId: &#39;xxxxx&#39;,</span><br><span class="line">     * name: &#39;xxx&#39;,</span><br><span class="line">     * intro: &#39;xxxx&#39;</span><br><span class="line">     * &#125;</span><br><span class="line">     * @apiErrorExample ErrorExample</span><br><span class="line">     * HTTP&#x2F;1.1 600</span><br><span class="line">     * 具体的异常信息</span><br><span class="line">     *&#x2F;</span><br><span class="line">    @GetMapping(&quot;&#x2F;&#123;id&#125;&quot;)</span><br><span class="line">    public Product getOneProduct(@PathVariable String id)</span><br><span class="line">    &#123;</span><br><span class="line">        return productServ.findOne(id);</span><br><span class="line">    &#125;</span><br><span class="line">12345678910111213141516171819202122</span><br></pre></td></tr></table></figure>

<p>常用的一些注解如下：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">@api 定义API的请求方法、路径和名字</span><br><span class="line">@apiDescription 定义API的描述</span><br><span class="line">@apiGroup 定义API的分组</span><br><span class="line">@apiParam 定义API的参数</span><br><span class="line">@apiParamExample 参数请求的事例</span><br><span class="line">@apiVersion 版本</span><br><span class="line">@apiErrorExample API错误示例</span><br><span class="line">@apiSuccessExample API正常示例</span><br><span class="line">12345678</span><br></pre></td></tr></table></figure>

<p>然后就可以利用apidoc的命令来生成接口文档了：<br><img src="https://note.youdao.com/yws/api/personal/file/3E3A42C7488F4B28A55A571E547E667E?method=download&shareKey=f4cb66a4dda2c461904f3d17ac6d480f" alt="img"></p>
<p>然后当前目录下会生成一个新的apidoc目录，就是新生成的接口文档文件。<br><img src="https://note.youdao.com/yws/api/personal/file/A32C6142B85F4DF5B6573298C86676F8?method=download&shareKey=0473103f88076c2f2e8890f7fca8a8f9" alt="img"></p>
<p>打开 index.html 即可看到生成的接口文档：<br><img src="https://note.youdao.com/yws/api/personal/file/953F265590674B73989A418C301FFE67?method=download&shareKey=09939a1241d68066e42a2e3a3faec42b" alt="img"></p>
<h3 id="2-swagger"><a href="#2-swagger" class="headerlink" title="2. swagger"></a>2. swagger</h3><p>在这里俺用 springBoot 整合swagger2 做了个Restful Api 的接口小demo</p>
<p><a href="https://github.com/caigoumiao/springboot-swagger" target="_blank" rel="noopener">github 源码传送门☛☛☛</a></p>
<p>首先项目中得添加swagger2的依赖：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line">&lt;!-- https:&#x2F;&#x2F;mvnrepository.com&#x2F;artifact&#x2F;io.springfox&#x2F;springfox-swagger2 --&gt;</span><br><span class="line">&lt;dependency&gt;</span><br><span class="line">    &lt;groupId&gt;io.springfox&lt;&#x2F;groupId&gt;</span><br><span class="line">    &lt;artifactId&gt;springfox-swagger2&lt;&#x2F;artifactId&gt;</span><br><span class="line">    &lt;version&gt;2.8.0&lt;&#x2F;version&gt;</span><br><span class="line">&lt;&#x2F;dependency&gt;</span><br><span class="line">&lt;!-- https:&#x2F;&#x2F;mvnrepository.com&#x2F;artifact&#x2F;io.springfox&#x2F;springfox-swagger-ui --&gt;</span><br><span class="line">&lt;dependency&gt;</span><br><span class="line">    &lt;groupId&gt;io.springfox&lt;&#x2F;groupId&gt;</span><br><span class="line">    &lt;artifactId&gt;springfox-swagger-ui&lt;&#x2F;artifactId&gt;</span><br><span class="line">    &lt;version&gt;2.8.0&lt;&#x2F;version&gt;</span><br><span class="line">&lt;&#x2F;dependency&gt;</span><br><span class="line">123456789101112</span><br></pre></td></tr></table></figure>

<p>创建swagger2 的配置类：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br></pre></td><td class="code"><pre><span class="line">@Configuration</span><br><span class="line">@EnableSwagger2</span><br><span class="line">public class SwaggerConfig</span><br><span class="line">&#123;</span><br><span class="line">    public Docket createApi()&#123;</span><br><span class="line">        return new Docket(DocumentationType.SWAGGER_2)</span><br><span class="line">                .apiInfo(apiInfo())</span><br><span class="line">                .select()</span><br><span class="line">                .apis(RequestHandlerSelectors.basePackage(&quot;com.miao.springbootswagger&quot;))</span><br><span class="line">                .paths(PathSelectors.any())</span><br><span class="line">                .build();</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    &#x2F;&#x2F; 创建api的基本信息</span><br><span class="line">    private ApiInfo apiInfo()&#123;</span><br><span class="line">        return new ApiInfoBuilder()</span><br><span class="line">                .title(&quot;springBoot 整合 Swagger2 实例&quot;)</span><br><span class="line">                .description(&quot;更多技术内容分享见博客：https:&#x2F;&#x2F;blog.csdn.net&#x2F;qq_24871519&quot;)</span><br><span class="line">                .termsOfServiceUrl(&quot;https:&#x2F;&#x2F;blog.csdn.net&#x2F;qq_24871519&quot;)</span><br><span class="line">                .version(&quot;1.0&quot;)</span><br><span class="line">                .build();</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line">1234567891011121314151617181920212223</span><br></pre></td></tr></table></figure>

<p>为接口添加swagger的注解：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br></pre></td><td class="code"><pre><span class="line">@RestController</span><br><span class="line">@RequestMapping(&quot;&#x2F;user&quot;)</span><br><span class="line">public class UserController</span><br><span class="line">&#123;</span><br><span class="line">    private static Map&lt;String, User&gt; users&#x3D;new ConcurrentHashMap&lt;&gt;();</span><br><span class="line"></span><br><span class="line">    @ApiOperation(value &#x3D; &quot;添加用户&quot;, notes &#x3D; &quot;添加一条用户信息&quot;)</span><br><span class="line">    @ApiImplicitParam(name &#x3D; &quot;user&quot;, value &#x3D; &quot;用户详细实体user&quot;, required &#x3D; true, dataType &#x3D; &quot;User&quot;)</span><br><span class="line">    @PostMapping(&quot;&#x2F;add&quot;)</span><br><span class="line">    public User add(User user)&#123;</span><br><span class="line">        String id&#x3D;UUID();</span><br><span class="line">        while(users.containsKey(id))&#123;</span><br><span class="line">            id&#x3D;UUID();</span><br><span class="line">        &#125;</span><br><span class="line">        user.setId(id);</span><br><span class="line">        users.put(id, user);</span><br><span class="line">        return user;</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    @ApiOperation(value &#x3D; &quot;获取一个用户&quot;, notes &#x3D; &quot;根据用户id获取用户信息&quot;)</span><br><span class="line">    @ApiImplicitParam(name &#x3D; &quot;id&quot;, value &#x3D; &quot;用户ID&quot;, required &#x3D; true, dataType &#x3D; &quot;String&quot;)</span><br><span class="line">    @GetMapping(&quot;&#x2F;&#123;id&#125;&quot;)</span><br><span class="line">    public User getOne(@PathVariable String id)&#123;</span><br><span class="line">        if(!users.containsKey(id))&#123;</span><br><span class="line">            return null;</span><br><span class="line">        &#125;</span><br><span class="line">        return users.get(id);</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    @ApiOperation(value &#x3D; &quot;获取所有用户信息列表&quot;)</span><br><span class="line">    @GetMapping(&quot;&#x2F;&quot;)</span><br><span class="line">    public List&lt;User&gt; getUsers()&#123;</span><br><span class="line">        return new ArrayList&lt;&gt;(users.values());</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    @ApiOperation(value &#x3D; &quot;更新用户信息&quot;)</span><br><span class="line">    @ApiImplicitParam(name &#x3D; &quot;user&quot;, value &#x3D; &quot;用户信息实体&quot;,required &#x3D; true, dataType &#x3D; &quot;User&quot;)</span><br><span class="line">    @PutMapping(&quot;&#x2F;&quot;)</span><br><span class="line">    public User updateOne(User u)&#123;</span><br><span class="line">        User tmp &#x3D; users.get(u.getId());</span><br><span class="line">        if(tmp &#x3D;&#x3D; null)&#123;</span><br><span class="line">            return null;</span><br><span class="line">        &#125;</span><br><span class="line">        if(u.getName()!&#x3D;null)&#123;</span><br><span class="line">            tmp.setName(u.getName());</span><br><span class="line">        &#125;</span><br><span class="line">        if(u.getAge() !&#x3D; null)&#123;</span><br><span class="line">            tmp.setAge(u.getAge());</span><br><span class="line">        &#125;</span><br><span class="line">        return tmp;</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    @ApiOperation(value &#x3D; &quot;删除用户&quot;)</span><br><span class="line">    @ApiImplicitParam(name &#x3D; &quot;id&quot;, value &#x3D; &quot;用户ID&quot;, required &#x3D; true, dataType &#x3D; &quot;String&quot;)</span><br><span class="line">    @DeleteMapping(&quot;&#x2F;&#123;id&#125;&quot;)</span><br><span class="line">    public void delete(@PathVariable String id)&#123;</span><br><span class="line">        if(users.containsKey(id))&#123;</span><br><span class="line">            users.remove(id);</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    private String UUID()&#123;</span><br><span class="line">        return UUID.randomUUID().toString().replace(&quot;-&quot;, &quot;&quot;);</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br><span class="line">1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465</span><br></pre></td></tr></table></figure>

<p>上述都完成后，启动springBoot 项目，访问 <a href="http://localhost/" target="_blank" rel="noopener">http://localhost</a>:/swagger-ui.html 即可访问接口文档页面，具体页面如下：<br><img src="https://note.youdao.com/yws/api/personal/file/8D095CF9E7CA47259ACB4DA34075E844?method=download&shareKey=9c3d003719cc502734c3739bbd6d5221" alt="img"></p>
<p><img src="https://note.youdao.com/yws/api/personal/file/1C94F35AE9A24495A8E2D1699C376FF2?method=download&shareKey=f5202a26d0dfa4e0e7e3a84d1804703c" alt="img"></p>
<h3 id="3、JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具"><a href="#3、JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具" class="headerlink" title="3、JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具"></a>3、JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具</h3><p>JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。</p>
<p>编写和维护API文档这个事情，对于后端程序员来说，是一件恼人但又不得不做的事情，我们都不喜欢写文档，但除非项目前后端代码都是自己写的，否则API文档将是前后端协作中一个不可或缺的沟通界面。</p>
<p>既然不可避免，那就想办法弄个轮子吧。人生苦短，必须偷懒。</p>
<p>相比Swagger要写一堆注解，Spring RestDocs需要写测试用例，才能生成API文档。JApiDocs 具有无痛集成的特点，你只需花几分钟就能知道它怎么用了。</p>
<p>快速开始</p>
<p>要使得JApiDcos正确工作，你写的代码应该是像下面的样子的：</p>
<figure class="highlight java"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br></pre></td><td class="code"><pre><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="comment">/**</span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">* 用户接口</span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">*/</span></span><br><span class="line"></span><br><span class="line"><span class="meta">@RequestMapping</span>(<span class="string">"/api/user/"</span>)</span><br><span class="line"></span><br><span class="line"><span class="meta">@RestController</span></span><br><span class="line"></span><br><span class="line">publicclassUserController&#123;</span><br><span class="line"></span><br><span class="line"><span class="comment">/**</span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">    * 用户列表</span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">*<span class="doctag">@paramlistForm</span></span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">    */</span></span><br><span class="line"></span><br><span class="line"><span class="meta">@RequestMapping</span>(path =<span class="string">"list"</span>, method = &#123;RequestMethod.GET,  RequestMethod.POST&#125;  )</span><br><span class="line"></span><br><span class="line">publicApiResult&gt; list(UserListForm listForm)&#123;</span><br><span class="line"></span><br><span class="line">returnnull;</span><br><span class="line"></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="comment">/**</span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">    * 保存用户</span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">*<span class="doctag">@paramuserForm</span></span></span><br><span class="line"><span class="comment"></span></span><br><span class="line"><span class="comment">    */</span></span><br><span class="line"></span><br><span class="line"><span class="meta">@PostMapping</span>(path =<span class="string">"save"</span>)</span><br><span class="line"></span><br><span class="line"><span class="function">publicApiResult <span class="title">saveUser</span><span class="params">(@RequestBodyUserForm userForm)</span></span>&#123;</span><br><span class="line"></span><br><span class="line">returnnull;</span><br><span class="line"></span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure>



<p>我们给Controller类和方法加上必要的注释，给接口方法返回相关的对象类型。是的，这样JApiDocs就能解析到相关的接口信息了，就跟我们平时写的代码是差不多的，但要注意，你要通过@param来告诉JApiDocs接口的参数，但在IDE的帮助下，这个工作将是轻松愉悦的：</p>
<p>然后你在任意一个main入口方法执行下面的代码就可以生成文档了：</p>
<figure class="highlight plain"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"></span><br><span class="line">DocsConfigconfig&#x3D; new DocsConfig();</span><br><span class="line"></span><br><span class="line">config.setProjectPath(&quot;your springboot project path&quot;); &#x2F;&#x2F; 项目根目录</span><br><span class="line"></span><br><span class="line">config.setProjectName(&quot;ProjectName&quot;); &#x2F;&#x2F; 项目名称</span><br><span class="line"></span><br><span class="line">config.setApiVersion(&quot;V1.0&quot;);      &#x2F;&#x2F; 声明该API的版本</span><br><span class="line"></span><br><span class="line">config.setDocsPath(&quot;your api docs path&quot;); &#x2F;&#x2F; 生成API 文档所在目录</span><br><span class="line"></span><br><span class="line">config.setAutoGenerate(Boolean.TRUE);  &#x2F;&#x2F; 配置自动生成</span><br><span class="line"></span><br><span class="line">Docs.buildHtmlDocs(config); &#x2F;&#x2F; 执行生成文档</span><br></pre></td></tr></table></figure>

<p>接下来你只管好好写代码，生成Api文档的工作就可以交给JApiDocs了，你不需要再为额外编写和维护文档而烦恼。</p>
<p>功能特性</p>
<p>1、代码即文档</p>
<p>JApiDocs是通过直接解析SpringBoot的源码语法来工作的，所以只要Controller的语法符合一定的代码规范，有合理的注释，就可以直接导出文档。</p>
<p>2、支持导出HTML</p>
<p>便捷的导航和接口查看界面；可本地预览，或者部署到HTTP服务器。推荐部署到服务器，方便前后端展开协作。</p>
<p>3、同步导出客户端Model代码</p>
<p>支持导出Android端的 Java 和iOS端的 Object C Model代码，减少前端程序员的重复编码工作。</p>
<p>4、更多特性</p>
<p>支持接口搜索；支持不同版本和英文文档；自定义扩展等。</p>
<p>简洁的文档</p>
<p>再好用的东西，如果没有文档说明，别人也无从入手。为了让大家尽快上手，JApiDocs准备了一份极简的文档说明，确保你在几分钟就能用上JApiDocs。</p>
<p>花5分钟不到就能认识一个提高工作效率的工具，让你把更多的时间花在更加有价值的事情上，你确认不看一下吗？</p>
<p>“</p>
<p>仓库地址：</p>
<p><a href="https://github.com/YeDaxia/JApiDocs" target="_blank" rel="noopener">https://github.com/YeDaxia/JApiDocs</a></p>
<p>中文文档：</p>
<p><a href="https://japidocs.agilestudio.cn/#/zh-cn/" target="_blank" rel="noopener">https://japidocs.agilestudio.cn/#/zh-cn/</a></p>

      
    </div>
    <footer class="article-footer">
      <a data-url="https://bianchengme.gitee.io/2020/09/09/Spring-boot-api-%E7%94%9F%E6%88%90%E5%B7%A5%E5%85%B7-apiDoc-vs-swagger-and-JApiDocs/" data-id="cktcaskhf00193gucfwfchn8i" class="article-share-link">Share</a>
      
      
    </footer>
  </div>
  
    
<nav id="article-nav">
  
    <a href="/2020/10/11/%E9%A1%B9%E7%9B%AE%E5%9F%BA%E7%BA%BF%E7%9B%AE%E5%BD%95-%E6%96%B9%E4%BE%BF%E9%A1%B9%E7%9B%AE%E7%AE%A1%E7%90%86%E4%B8%8E%E4%BA%A4%E6%8E%A5/" id="article-nav-newer" class="article-nav-link-wrap">
      <strong class="article-nav-caption">Newer</strong>
      <div class="article-nav-title">
        
          项目基线目录-方便项目管理与交接
        
      </div>
    </a>
  
  
    <a href="/2020/08/09/Java-enum%E5%B8%B8%E8%A7%81%E7%9A%84%E7%94%A8%E6%B3%95/" id="article-nav-older" class="article-nav-link-wrap">
      <strong class="article-nav-caption">Older</strong>
      <div class="article-nav-title">Java enum常见的用法</div>
    </a>
  
</nav>

  
</article>

</section>
        
          <aside id="sidebar">
  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Categories</h3>
    <div class="widget">
      <ul class="category-list"><li class="category-list-item"><a class="category-list-link" href="/categories/Docker/">Docker</a><ul class="category-list-child"><li class="category-list-item"><a class="category-list-link" href="/categories/Docker/Nacos/">Nacos</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/Docker/mysql/">mysql</a></li></ul></li><li class="category-list-item"><a class="category-list-link" href="/categories/JAVA/">JAVA</a><ul class="category-list-child"><li class="category-list-item"><a class="category-list-link" href="/categories/JAVA/JVM/">JVM</a></li></ul></li><li class="category-list-item"><a class="category-list-link" href="/categories/Markdown/">Markdown</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/Windows/">Windows</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/docker/">docker</a><ul class="category-list-child"><li class="category-list-item"><a class="category-list-link" href="/categories/docker/redis/">redis</a></li></ul></li><li class="category-list-item"><a class="category-list-link" href="/categories/flutter/">flutter</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/git/">git</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/iOS/">iOS</a><ul class="category-list-child"><li class="category-list-item"><a class="category-list-link" href="/categories/iOS/Objective-C/">Objective-C</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/iOS/Xcode/">Xcode</a></li></ul></li><li class="category-list-item"><a class="category-list-link" href="/categories/java/">java</a><ul class="category-list-child"><li class="category-list-item"><a class="category-list-link" href="/categories/java/%E5%A4%9A%E7%BA%BF%E7%A8%8B/">多线程</a></li></ul></li><li class="category-list-item"><a class="category-list-link" href="/categories/mysql/">mysql</a></li><li class="category-list-item"><a class="category-list-link" href="/categories/vue/">vue</a></li></ul>
    </div>
  </div>


  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Tags</h3>
    <div class="widget">
      <ul class="tag-list" itemprop="keywords"><li class="tag-list-item"><a class="tag-list-link" href="/tags/BUG/" rel="tag">BUG</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/Docker/" rel="tag">Docker</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/JAVA/" rel="tag">JAVA</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/JVM/" rel="tag">JVM</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/Markdown/" rel="tag">Markdown</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/Objective-C/" rel="tag">Objective-C</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/RunTime/" rel="tag">RunTime</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/Swift/" rel="tag">Swift</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/UI/" rel="tag">UI</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/Windows/" rel="tag">Windows</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/Xcode/" rel="tag">Xcode</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/docker/" rel="tag">docker</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/flutter/" rel="tag">flutter</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/git/" rel="tag">git</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/hook/" rel="tag">hook</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/iOS/" rel="tag">iOS</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/iOS%E7%9C%9F%E6%9C%BA%E8%BF%90%E8%A1%8C/" rel="tag">iOS真机运行</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/java/" rel="tag">java</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/mysl/" rel="tag">mysl</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/mysql/" rel="tag">mysql</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/nacos/" rel="tag">nacos</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/redis/" rel="tag">redis</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/volatile/" rel="tag">volatile</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/vue/" rel="tag">vue</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E4%BC%98%E5%8C%96/" rel="tag">优化</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E5%A4%9A%E7%BA%BF%E7%A8%8B/" rel="tag">多线程</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E5%AD%A6%E4%B9%A0%E8%AE%A1%E5%88%92/" rel="tag">学习计划</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E5%B7%A5%E5%85%B7/" rel="tag">工具</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E5%B9%B6%E5%8F%91%E7%BC%96%E7%A8%8B/" rel="tag">并发编程</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E7%AE%97%E6%B3%95/" rel="tag">算法</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E7%BD%91%E7%BB%9C/" rel="tag">网络</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E9%83%A8%E7%BD%B2/" rel="tag">部署</a></li><li class="tag-list-item"><a class="tag-list-link" href="/tags/%E9%9D%A2%E8%AF%95/" rel="tag">面试</a></li></ul>
    </div>
  </div>


  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Tag Cloud</h3>
    <div class="widget tagcloud">
      <a href="/tags/BUG/" style="font-size: 10px;">BUG</a> <a href="/tags/Docker/" style="font-size: 10px;">Docker</a> <a href="/tags/JAVA/" style="font-size: 10px;">JAVA</a> <a href="/tags/JVM/" style="font-size: 10px;">JVM</a> <a href="/tags/Markdown/" style="font-size: 10px;">Markdown</a> <a href="/tags/Objective-C/" style="font-size: 16.67px;">Objective-C</a> <a href="/tags/RunTime/" style="font-size: 10px;">RunTime</a> <a href="/tags/Swift/" style="font-size: 10px;">Swift</a> <a href="/tags/UI/" style="font-size: 13.33px;">UI</a> <a href="/tags/Windows/" style="font-size: 10px;">Windows</a> <a href="/tags/Xcode/" style="font-size: 10px;">Xcode</a> <a href="/tags/docker/" style="font-size: 13.33px;">docker</a> <a href="/tags/flutter/" style="font-size: 13.33px;">flutter</a> <a href="/tags/git/" style="font-size: 10px;">git</a> <a href="/tags/hook/" style="font-size: 10px;">hook</a> <a href="/tags/iOS/" style="font-size: 20px;">iOS</a> <a href="/tags/iOS%E7%9C%9F%E6%9C%BA%E8%BF%90%E8%A1%8C/" style="font-size: 10px;">iOS真机运行</a> <a href="/tags/java/" style="font-size: 16.67px;">java</a> <a href="/tags/mysl/" style="font-size: 10px;">mysl</a> <a href="/tags/mysql/" style="font-size: 10px;">mysql</a> <a href="/tags/nacos/" style="font-size: 10px;">nacos</a> <a href="/tags/redis/" style="font-size: 10px;">redis</a> <a href="/tags/volatile/" style="font-size: 10px;">volatile</a> <a href="/tags/vue/" style="font-size: 10px;">vue</a> <a href="/tags/%E4%BC%98%E5%8C%96/" style="font-size: 10px;">优化</a> <a href="/tags/%E5%A4%9A%E7%BA%BF%E7%A8%8B/" style="font-size: 10px;">多线程</a> <a href="/tags/%E5%AD%A6%E4%B9%A0%E8%AE%A1%E5%88%92/" style="font-size: 10px;">学习计划</a> <a href="/tags/%E5%B7%A5%E5%85%B7/" style="font-size: 10px;">工具</a> <a href="/tags/%E5%B9%B6%E5%8F%91%E7%BC%96%E7%A8%8B/" style="font-size: 10px;">并发编程</a> <a href="/tags/%E7%AE%97%E6%B3%95/" style="font-size: 10px;">算法</a> <a href="/tags/%E7%BD%91%E7%BB%9C/" style="font-size: 10px;">网络</a> <a href="/tags/%E9%83%A8%E7%BD%B2/" style="font-size: 10px;">部署</a> <a href="/tags/%E9%9D%A2%E8%AF%95/" style="font-size: 10px;">面试</a>
    </div>
  </div>

  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Archives</h3>
    <div class="widget">
      <ul class="archive-list"><li class="archive-list-item"><a class="archive-list-link" href="/archives/2021/09/">September 2021</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2021/07/">July 2021</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2021/06/">June 2021</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2021/05/">May 2021</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2021/03/">March 2021</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/10/">October 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/09/">September 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/08/">August 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/07/">July 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/05/">May 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/04/">April 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2020/03/">March 2020</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2019/06/">June 2019</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2019/05/">May 2019</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2019/04/">April 2019</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2019/03/">March 2019</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2019/02/">February 2019</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2018/10/">October 2018</a></li><li class="archive-list-item"><a class="archive-list-link" href="/archives/2018/03/">March 2018</a></li></ul>
    </div>
  </div>


  
    
  <div class="widget-wrap">
    <h3 class="widget-title">Recent Posts</h3>
    <div class="widget">
      <ul>
        
          <li>
            <a href="/2021/09/07/JVM-%E9%80%83%E9%80%B8%E5%88%86%E6%9E%90%E4%BC%98%E5%8C%96/">JVM 逃逸分析优化</a>
          </li>
        
          <li>
            <a href="/2021/07/02/Nacos%E9%80%9A%E8%BF%87Docke%E9%83%A8%E7%BD%B2/">Nacos通过Docke部署</a>
          </li>
        
          <li>
            <a href="/2021/07/01/Docker%E5%AE%89%E8%A3%85mysql5-7/">Docker安装mysql5.7</a>
          </li>
        
          <li>
            <a href="/2021/07/01/Docker%E5%AE%89%E8%A3%85redis/">Docker安装redis</a>
          </li>
        
          <li>
            <a href="/2021/06/30/Java%E5%B9%B6%E5%8F%91%E7%BC%96%E7%A8%8B-volatile%E5%85%B3%E9%94%AE%E5%AD%97%E7%90%86%E8%A7%A3/">Java并发编程-volatile关键字理解</a>
          </li>
        
      </ul>
    </div>
  </div>

  
</aside>
        
      </div>
      <footer id="footer">
  
  <div class="outer">
    <div id="footer-info" class="inner">
      &copy; 2021 jmme@foxmail.com<br>
      Powered by <a href="http://hexo.io/" target="_blank">Hexo</a>
    </div>
  </div>
</footer>
    </div>
    <nav id="mobile-nav">
  
    <a href="/" class="mobile-nav-link">Home</a>
  
    <a href="/archives" class="mobile-nav-link">Archives</a>
  
</nav>
    

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>


  
<link rel="stylesheet" href="/fancybox/jquery.fancybox.css">

  
<script src="/fancybox/jquery.fancybox.pack.js"></script>




<script src="/js/script.js"></script>




  </div>
</body>
</html>